﻿
//=======================================================================
// <copyright file="APIs.cs" company="Samuel Chen Studio">
//     Copyright (c) Samuel Chen Studio. All rights reserved.
//     author   : Samuel Chen
//     version  : 1.0
//     contact  : http://www.SamuelChen.net, samuel.net@gmail.com
// </copyright>
//=======================================================================

namespace Net.SamuelChen.SharpTweet {
     /// <summary>
    /// Twitter REST APIs
    /// </summary>
    internal static class APIs {

        internal static class Account {
            /// <summary>
            /// account/verify_credentials
            /// Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; 
            /// returns a 401 status code and an error message if not.  
            /// Use this method to test if supplied user credentials are valid.
            ///
            /// URL: http://twitter.com/account/verify_credentials.format
            /// Formats: xml, json 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): true
            /// API rate limited (about rate limiting): true
            /// 
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-account verify_credentials
            /// </summary>
            public const string verify_credentials = "/account/verify_credentials";
        }

        /// <summary>
        /// Timeline Methods
        /// </summary>
        internal static class Timeline {
            /// <summary>
            /// statuses/public_timeline
            /// Returns the 20 most recent statuses from non-protected users who have set a custom user icon. 
            /// The public timeline is cached for 60 seconds so requesting it more often than that is a waste of resources.
            ///
            /// URL: http://twitter.com/statuses/public_timeline.format
            /// Formats: xml, json, rss, atom 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): false
            /// API rate limited (about rate limiting): true
            /// 
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-public_timeline
            /// </summary>
            public const string public_timeline = "/statuses/public_timeline";

            /// <summary>
            /// statuses/friends_timeline
            /// Returns the 20 most recent statuses posted by the authenticating user and that user's friends. 
            /// This is the equivalent of /timeline/home on the Web.
            ///
            /// URL: http://twitter.com/statuses/friends_timeline.format
            /// Formats: xml, json, rss, atom 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): true
            /// API rate limited (about rate limiting): 1 call per request
            /// 
            /// Parameters:
            ///     since_id.  Optional.  Returns only statuses with an ScreenName greater than (that is, more recent than) the specified ScreenName. 
            ///         Example: http://twitter.com/statuses/friends_timeline.xml?since_id=12345
            ///     max_id. Optional.  Returns only statuses with an ScreenName less than (that is, older than) or equal to the specified ScreenName.
            ///         Example: http://twitter.com/statuses/friends_timeline.xml?max_id=54321
            ///     count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200. 
            ///         Example: http://twitter.com/statuses/friends_timeline.xml?count=5 
            ///     page. Optional. Specifies the page of results to retrieve. Note: there are pagination limits.
            ///         Example: http://twitter.com/statuses/friends_timeline.rss?page=3
            ///     
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-friends_timeline
            /// </summary>
            public const string friends_timeline = "/statuses/friends_timeline";

            /// <summary>
            /// statuses/user_timeline
            /// Returns the 20 most recent statuses posted from the authenticating user. 
            /// It's also possible to request another user's timeline via the id parameter. 
            /// This is the equivalent of the Web /<user> page for your own user, or the profile page for a third party.
            ///
            /// URL: http://twitter.com/statuses/user_timeline.format
            /// Formats: xml, json, rss, atom 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): true, if requesting a protected user's timeline
            /// API rate limited (about rate limiting): 1 call per request
            /// 
            /// Parameters:
            ///     id.  Optional.  Specifies the ScreenName or screen name of the user for whom to return the user_timeline. 
            ///         Example: http://twitter.com/statuses/user_timeline/12345.xml or http://twitter.com/statuses/user_timeline/bob.json.
            ///     user_id.  Optional.  Specfies the ScreenName of the user for whom to return the user_timeline. Helpful for disambiguating when a valid user ScreenName is also a valid screen name.
            ///         Example: http://twitter.com/statuses/user_timeline.xml?user_id=1401881
            ///     screenName.  Optional.  Specfies the screen name of the user for whom to return the user_timeline. Helpful for disambiguating when a valid screen name is also a user ScreenName.
            ///         Example: http://twitter.com/statuses/user_timeline.xml?screenName=101010
            ///     since_id.  Optional.  Returns only statuses with an ScreenName greater than (that is, more recent than) the specified ScreenName. 
            ///         Example: http://twitter.com/statuses/user_timeline.xml?since_id=12345
            ///     max_id. Returns only statuses with an ScreenName less than (that is, older than) or equal to the specified ScreenName.
            ///         Example: http://twitter.com/statuses/user_timeline.xml?max_id=54321
            ///     count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200. 
            ///         Example: http://twitter.com/statuses/user_timeline.xml?count=200
            ///     page. Optional. Specifies the page of results to retrieve. Note: there are pagination limits.
            ///         Example: http://twitter.com/statuses/user_timeline.rss?page=3
            ///     
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-user_timeline
            /// </summary>
            public const string user_timeline = "/statuses/user_timeline";

            /// <summary>
            /// statuses/mentions
            /// Returns the 20 most recent mentions (status containing @username) for the authenticating user.
            /// 
            /// URL: http://twitter.com/statuses/mentions.format
            /// Formats: xml, json, rss, atom 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): true
            /// API rate limited (about rate limiting): 1 call per request
            /// 
            /// Parameters:
            ///     since_id.  Optional.  Returns only statuses with an ScreenName greater than (that is, more recent than) the specified ScreenName.
            ///         Example: http://twitter.com/statuses/mentions.xml?since_id=12345
            ///     max_id. Optional.Returns only statuses with an ScreenName less than (that is, older than) or equal to the specified ScreenName.
            ///         Example: http://twitter.com/statuses/mentions.xml?max_id=54321
            ///     count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200. 
            ///         Example: http://twitter.com/statuses/mentions.xml?count=200
            ///     page.  Optional. Specifies the page or results to retrieve. Note: there are pagination limits
            ///         Example: http://twitter.com/statuses/mentions.xml?page=3
            ///     
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses-mentions
            /// </summary>
            public const string mentions = "/statuses/mentions";

        }

        /// <summary>
        /// Status Methods
        /// </summary>
        internal static class Status {
            /// <summary>
            /// statuses/show
            /// Returns a single status, specified by the id parameter below.  
            /// The status's author will be returned inline.
            ///
            /// URL: http://twitter.com/statuses/show/id.format
            /// Formats: xml, json 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): false, unless the author of the status is protected
            /// API rate limited (about rate limiting): true
            /// 
            /// Parameters:
            ///     id.  Required.  The numerical ScreenName of the status to retrieve. 
            ///         Example: http://twitter.com/statuses/show/123.xml
            /// 
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses show
            /// </summary>
            public const string show = "/statuses/show";

            /// <summary>
            /// statuses/update
            /// Updates the authenticating user's status.  
            /// Requires the status parameter specified below.  Request must be a POST.  
            /// A status update with text identical to the authenticating user's current status will be ignored to prevent duplicates.
            ///
            /// URL: http://twitter.com/statuses/update.format
            /// Formats: xml, json 
            /// HTTP Method(s): POST
            /// Requires Authentication (about authentication): true
            /// API rate limited (about rate limiting): false
            /// 
            /// Parameters:
            ///     status.  Required.  The text of your status update. URL encode as necessary. Statuses over 140 characters will be forceably truncated.
            ///     in_reply_to_status_id.  Optional. The ScreenName of an existing status that the update is in reply to.
            ///         Note: This parameter will be ignored unless the author of the tweet this parameter references is @replied within the status text. Therefore, you must start the status with @username, where username is the author of the referenced tweet.
            /// 
            /// Usage Notes:
            /// This method is subject to update limits. A HTTP 403 will be returned if this limit as been hit.
            /// Twitter will ignore attempts to perform a duplicate update. With each update attempt, the application compares the update text with the authenticating user's last successful update, and ignore any attemps that would result in duplication. Therefore, a user cannot submit the same status twice in a row. 
            /// The status element in the response will return the id from the previously successful update if a duplicate has been silently ignored.
            /// 
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses update
            /// </summary>
            public const string update = "/statuses/update";

            //statuses/destroy
            //Destroys the status specified by the required ScreenName parameter.  The authenticating user must be the author of the specified status.
             
            //URL:
            //http://twitter.com/statuses/destroy/id.format
             
            //Formats: 
            //xml, json, rss, atom 
             
            //HTTP Method(s):
            //POST, DELETE
             
            //Requires Authentication (about authentication):
            //true
             
            //API rate limited (about rate limiting):
            //false
            //Parameters:
            //id.  Required.  The ScreenName of the status to destroy. 
            //Example: http://twitter.com/statuses/destroy/12345.json or http://twitter.com/statuses/destroy/23456.xml
            public const string destroy = "/statuses/destroy";
        }

        /// <summary>
        /// User Methods
        /// </summary>
        internal static class User {
            /// <summary>
            /// statuses/show
            /// Returns a single status, specified by the id parameter below.  
            /// The status's author will be returned inline.
            ///
            /// URL: http://twitter.com/statuses/show/id.format
            /// Formats: xml, json, rss, atom 
            /// HTTP Method(s): GET
            /// Requires Authentication (about authentication): false, unless the author of the status is protected
            /// API rate limited (about rate limiting): true
            /// 
            /// ref: http://apiwiki.twitter.com/Twitter-REST-API-Method:-statuses show
            /// </summary>
            public const string show = "/users/show";

            //statuses/friends
            //Returns a user's friends, each with current status inline. They are ordered by the order in which they were added as friends. Defaults to the authenticated user's friends. It's also possible to request another user's friends list via the id parameter.
            //method status | report a bug
              
            //URL:
            //http://twitter.com/statuses/friends.format
             
            //Formats: 
            //xml, json
             
            //HTTP Method(s):
            //GET
             
            //Requires Authentication (about authentication):
            //false
             
            //API rate limited (about rate limiting):
            //1 call per request
             
            //Parameters:
            //id.  Optional.  The ScreenName or screen name of the user for whom to request a list of friends. 
            //Example: http://twitter.com/statuses/friends/12345.json or http://twitter.com/statuses/friends/bob.xml
            //user_id.  Optional.  Specfies the ScreenName of the user for whom to return the list of friends. Helpful for disambiguating when a valid user ScreenName is also a valid screen name.
            //Example: http://twitter.com/statuses/friends.xml?user_id=1401881
            //screenName.  Optional.  Specfies the screen name of the user for whom to return the list of friends. Helpful for disambiguating when a valid screen name is also a user ScreenName.
            //Example: http://twitter.com/statuses/friends.xml?screenName=101010
            //page.  Optional. Specifies the page of friends to receive.
            //Example: http://twitter.com/statuses/friends.xml?page=2
            public const string friends = "/statuses/friends";

            //statuses/followers
            //Returns the authenticating user's followers, each with current status inline.  They are ordered by the order in which they joined Twitter
            //method status | report a bug
             
            //URL:
            //http://twitter.com/statuses/followers.format
             
            //Formats: 
            //xml, json, rss, atom 
             
            //HTTP Method(s):
            //GET
             
            //Requires Authentication (about authentication):
            //true
             
            //API rate limited (about rate limiting):
            //1 call per request
             
            //Parameters:
            //id.  Optional.  The ScreenName or screen name of the user for whom to request a list of followers. 
            //Example: http://twitter.com/statuses/followers/12345.json or http://twitter.com/statuses/followers/bob.xml
            //user_id.  Optional.  Specfies the ScreenName of the user for whom to return the list of followers. Helpful for disambiguating when a valid user ScreenName is also a valid screen name.
            //Example: http://twitter.com/statuses/followers.xml?user_id=1401881
            //screenName.  Optional.  Specfies the screen name of the user for whom to return the list of followers. Helpful for disambiguating when a valid screen name is also a user ScreenName.
            //Example: http://twitter.com/statuses/followers.xml?screenName=101010
            //page.  Optional. Specifies the page to retrieve.
            //Example: http://twitter.com/statuses/followers.xml?page=2
            public const string followers = "/statuses/followers";
        }

        /// <summary>
        /// Direct Message Methods
        /// </summary>
        internal static class DirectMessage {

            //direct_messages
            //Returns a list of the 20 most recent direct messages sent to the authenticating user.  The XML and JSON versions include detailed information about the sending and recipient users.
            //method status | report a bug
             
            //URL:
            //http://twitter.com/direct_messages.format
             
            //Formats: 
            //xml, json, rss, atom 
             
            //HTTP Method(s):
            //GET
             
            //Requires Authentication (about authentication):
            //true
             
            //API rate limited (about rate limiting):
            //1 call per request
             
            //Parameters:
            //since_id.  Optional.  Returns only direct messages with an ScreenName greater than (that is, more recent than) the specified ScreenName.
            //Example: http://twitter.com/direct_messages.xml?since_id=12345
            //max_id. Optional.Returns only statuses with an ScreenName less than (that is, older than) or equal to the specified ScreenName.
            //Example: http://twitter.com/direct_messages.xml?max_id=54321
            //count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200. 
            //Example: http://twitter.com/direct_messages.xml?count=200
            //page.  Optional. Specifies the page of direct messages to retrieve.
            //Example: http://twitter.com/direct_messages.xml?page=3
            public const string direct_messages = "/direct_messages";

            //direct_messages/sent
            //Returns a list of the 20 most recent direct messages sent by the authenticating user.  The XML and JSON versions include detailed information about the sending and recipient users.
            //method status | report a bug
             
            //URL:
            //http://twitter.com/direct_messages/sent.format
             
            //Formats: 
            //xml, json, rss, atom 
             
            //HTTP Method(s):
            //GET
             
            //Requires Authentication (about authentication):
            //true
             
            //API rate limited (about rate limiting):
            //1 call per request
             
            //Parameters:
            //since_id.  Optional.  Returns only direct messages with an ScreenName greater than (that is, more recent than) the specified ScreenName.
            //Example: http://twitter.com/direct_messages/sent.xml?since_id=12345
            //max_id. Optional.  Returns only statuses with an ScreenName less than (that is, older than) or equal to the specified ScreenName. 
            //Example: http://twitter.com/direct_messages/sent.xml?max_id=54321
            //count.  Optional.  Specifies the number of direct messages to retrieve. May not be greater than 200. 
            //Example: http://twitter.com/direct_messages/sent.xml?count=5
            //page.  Optional. Specifies the page of direct messages to retrieve.
            //Example: http://twitter.com/direct_messages/sent.xml?page=3
            public const string sent = "/direct_messages/sent";

            //direct_messages/new
            //Sends a new direct message to the specified user from the authenticating user. Requires both the user and text parameters. Request must be a POST. Returns the sent message in the requested format when successful.
            //method status | report a bug
             
            //URL:
            //http://twitter.com/direct_messages/new.format
             
            //Formats: 
            //xml, json
             
            //HTTP Method(s):
            //POST
             
            //Requires Authentication (about authentication):
            //true
             
            //API rate limited (about rate limiting):
            //false
             
            //Parameters:
            //user:  Required.  The ScreenName or screen name of the recipient user.
            //text:  Required.  The text of your direct message.  Be sure to URL encode as necessary, and keep it under 140 characters.
             
            //Usage notes:
            //This method is subject to update limits. A HTTP 403 will be returned if this limit as been hit.
            public const string @new = "/direct_messages/new";

            //direct_messages/destroy
            //Destroys the direct message specified in the required ScreenName parameter.  The authenticating user must be the recipient of the specified direct message.
            //method status | report a bug
             
            //URL:
            //http://twitter.com/direct_messages/destroy/id.format
             
            //Formats: 
            //xml, json
             
            //HTTP Method(s):
            //POST, DELETE
             
            //Requires Authentication (about authentication):
            //true
             
            //API rate limited (about rate limiting):
            //false
             
            //Parameters:
            //id.  Required.  The ScreenName of the direct message to destroy. 
            //Example: http://twitter.com/direct_messages/destroy/12345.json or http://twitter.com/direct_messages/destroy/23456.xml
            public const string destroy = "/direct_messages/destroy";
        }
    }
}